home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / a86v307a.arc / 03OPREQ.DOC < prev    next >
Text File  |  1987-07-13  |  13KB  |  284 lines
  1. CHAPTER 3   OPERATION AND REQUIREMENTS                    3-1
  2.  
  3.  
  4. A86 Program Invocation
  5.  
  6. To invoke A86, you must provide a program invocation line, either 
  7. typed to the console when the DOS command prompt appears, or 
  8. included in a batch file.  The program invocation line consists 
  9. of the following: 
  10.  
  11. 1. The program name A86.
  12.  
  13. 2. The names of the source files you want to assemble.  You may 
  14.    use the wild-card delimiters * and ? if you wish, to denote a 
  15.    group of source files to be assembled.  A86 will sort all 
  16.    matching names into alphabetical order for each wild-card 
  17.    specification; so the files will be assembled in the same 
  18.    order even if they get jumbled up within a directory.  
  19.  
  20.    A86 identifies the end of the source file names when it sees a 
  21.    name with no extension, or a name with the default object-
  22.    extension (COM, BIN or OBJ, as described shortly).  Sorry, you 
  23.    cannot have a source file with the default object extension.  
  24.  
  25. 3. You may optionally provide the word TO, to separate the source 
  26.    file names from the output file names.  
  27.  
  28. 4. The name of the output program.  If you do not provide an 
  29.    extension, A86 will assume one of the following extensions:
  30.  
  31.      a. .OBJ if you invoked the +O switch, for linkable-object
  32.         file production.
  33.  
  34.      b. .BIN if there is no +O switch, but there is an ORG 0 in 
  35.         your program.
  36.  
  37.      c. .COM otherwise.
  38.  
  39.    If you want your program file to have no extension, you end 
  40.    the file name with a period.  
  41.  
  42.    You have the option to omit both the program file name and the 
  43.    symbol table file name from the invocation.  If you do so, A86 
  44.    will output the program source.COM (or source.OBJ or 
  45.    source.BIN) and the symbol table source.SYM; where "source" is 
  46.    a name derived from the list of source files, according to the 
  47.    rules described in the section "Strategies for Source File 
  48.    Maintenance" later in this chapter.  
  49.  
  50. 5. The name of the symbol-table file.  If you do not provide an 
  51.    extension, A86 will assume that you want the extension .SYM.  
  52.    If you want your symbol table file to have no extension, you 
  53.    end the file name with a period.  
  54.  
  55.    You have the option to omit the name of the symbol table file.  
  56.    If you do so, A86 will use the same root as the output program 
  57.    name, with a .SYM extension.  If you desire no symbol table 
  58.    file, specify the +S switch in your invocation line or A86 
  59.    environment variable.
  60.                                                           3-2
  61. Assembler Switches
  62.  
  63. In addition to input and output file names, you may intersperse 
  64. assembler switch-settings anywhere after the A86 program name.  
  65. They are all acted upon immediately, no matter where they are on 
  66. the command line.  Some of the switches are discussed in more 
  67. detail elsewhere; we summarize them here: 
  68.  
  69. +C  causes the assembler to be sensitive to upper- vs. lower-case
  70. +c  for all symbols, so that routines with lower-case names can 
  71.     be created for linking to C programs.  WARNING: I provide 
  72.     only limited support for this right now.  In particular, if 
  73.     you use this option, you MUST give all built-in symbol names 
  74.     in ALL CAPS if you specified a capital letter +C, or all 
  75.     lower-case if you specified a lower-case letter +c.  And D86 
  76.     doesn't recognize this yet-- although D86 will correctly 
  77.     disassemble symbols containing lower-case letters, you won't 
  78.     be able to refer to such symbols in D86 commands, because D86 
  79.     will convert your references to all-upper-case. 
  80.  
  81. -C  causes A86 to ignore upper- vs. lower-case in all symbol 
  82.     names.
  83.  
  84. +D  causes the default base for numeric constants to be decimal, 
  85.     even if the constants have leading zeroes.
  86.  
  87. -D  causes the default base to be hexadecimal if there is a 
  88.     leading zero; decimal otherwise.
  89.  
  90. +E  causes the error-message-augmented source file to be written 
  91.     to yourname.ERR within the current directory, in all cases.  
  92.     With +E, A86 will never rewrite your original source file. 
  93.  
  94. -E  causes A86 to insert error messages into your source file,
  95.     whenever the file is in the current directory.  If the file 
  96.     is not in the current directory, A86 write an ERR file no 
  97.     matter what the E-switch setting is.
  98.  
  99. +F  causes A86 to generate the 287-form of floating-point 
  100.     instructions (no implicit FWAIT bytes are generated before 
  101.     the instructions).  This mode can also be specified in the 
  102.     program with the .287 directive.
  103.  
  104. +f  causes A86 to support emulation of the 8087.  When A86 sees a 
  105.     floating-point instruction, it generates external references 
  106.     to be resolved by the standard emulation library (provided by 
  107.     Microsoft, Borland, etc.).  When you LINK your program to the 
  108.     emulation library, the floating-point instructions are 
  109.     emulated by software.  NOTE you must be assembling to a 
  110.     linkable OBJ file for this mode to have effect; otherwise, +f 
  111.     is ignored.
  112.  
  113. -F  causes emulation and default-287 to be disabled.  You'll 
  114.     still get 287 generation if there is a .287 directive in your 
  115.     program.        
  116.                                                           3-3 
  117. +L  causes A86 to generate a longer (3-byte) instruction form 
  118.     for an unconditional JMP instruction to a forward-reference 
  119.     local labels, e.g. JMP >L1.  The code will usually be longer 
  120.     than necessary, but you'll be spared having to occasionally 
  121.     go back and code an explicit JMP LONG >L1.
  122.  
  123. -L  causes A86 to generate the more efficient 2-byte form for
  124.     JMP >L1.
  125.  
  126. +O  causes A86 to produce a linkable .OBJ file when the output 
  127.     file name extension is not explicitly given.
  128.  
  129. -O  causes A86 to produce an executable .COM file when the output 
  130.     file name extension is not explicitly given.
  131.  
  132. +S  suppresses the creation of the symbol-table (.SYM) file in 
  133.     normal (no errors) assembly.  This is overridden if you give 
  134.     an explicit symbols-file name in the invocation line.
  135.  
  136. -S  causes the symbol-table file to be created in all cases.
  137.  
  138. +X  causes A86 to require that undefined names be explicitly 
  139.     declared with an EXTRN when A86 is producing a linkable .OBJ 
  140.     file.  The X switch has no effect when A86 is making a .COM 
  141.     file.
  142.  
  143. -X  causes A86 to quietly assume that all undefined names are 
  144.     valid external references.
  145.     
  146. The default setting for all the switches is "minus".  Multiple 
  147. switches can be specified with a single sign; e.g. +OX is the 
  148. same as +O+X.
  149.  
  150.  
  151.  
  152. The A86 Environment Variable
  153.  
  154. To allow you to customize A86, the assembler examines the 
  155. MS-DOS environment variable named "A86" when it is invoked.  If 
  156. there is such a variable, its contents are inserted before the 
  157. invocation command tail, as if you had typed them yourself.
  158.  
  159. For example, if you execute the command SET A86=+OX while in DOS 
  160. (typically in the AUTOEXEC.BAT file run when the computer is 
  161. started), then the O and X siwtches will be "plus", unless 
  162. overridden with a "minus" setting in the command line.             
  163.  
  164. You may also include one or more file names in the A86 
  165. environment variable.  Those files will always be assembled 
  166. first, before the files you specify on the command line.  This 
  167. allows you to set up a library of macro definitions, which will 
  168. always be automatically available to your programs.  Thus, for 
  169. example, the DOS command  SET A86=C:\A86\MACDEF.8 +OX  will cause 
  170. both the O and X switches to default ON, but will also cause the 
  171. file MACDEF.8 of subdirectory A86 of drive C to always be 
  172. assembled.
  173.                                                           3-4
  174. Using Standard Input as a Command Tail
  175.  
  176. The following feature is a bit advanced.  If you're not familiar 
  177. with the practice of redirecting standard input, you may safely 
  178. skip this section.
  179.  
  180. A86 can also be configured to take its command arguments from 
  181. standard input, in addition to the invoaction command tail or the 
  182. A86 environment variable.  This allows A86 to be used in those 
  183. menu-driven systems that don't generate command tails for 
  184. programs.  It also allows other programs to create lists of files 
  185. to be assembled, then "pipe" the list to A86. 
  186.  
  187. Here's how the feature works: when the command argument A86 is an 
  188. ampersand &, A86 will prompt for standard input.  If the 
  189. ampersand is seen but there are other things following it, the 
  190. ampersand is ignored.
  191.  
  192. For example, you can place a list of file names and switch 
  193. settings into a file called FILELIST.  You can then invoke the 
  194. assembler via
  195.  
  196. A86 <FILELIST &
  197.  
  198. which will cause the contents of the FILELIST file to be used as 
  199. a command line.
  200.  
  201. You may place an ampersand at the end of your A86 environment 
  202. variable.  If you do so, then A86 will prompt for file names 
  203. whenever it is invoked without any command arguments (you type 
  204. A86 followed immediately by the ENTER key to the MS-DOS prompt).
  205. This is the mode used if you have a menu system that can't 
  206. generate an invocation command tail.
  207.  
  208. Note: when you redirect standard input so that it comes from a 
  209. file, A86 will read all the lines of the file (up to a limit of 
  210. 1023 bytes), and substitute spaces for the line breaks.  Thus you 
  211. may give the file names on individual lines, for readability.  
  212. However, if the feature is invoked manually (no redirection), so 
  213. that you are typing in the line after the prompt, A86 will take 
  214. the first line only.  You need to give all your switches and 
  215. files on that one line. 
  216.  
  217.  
  218.  
  219. Strategies for Source File Maintenance
  220.  
  221. A86 encourages modular programming, by letting you break your 
  222. source into separate files, with complete impunity.  A86 has no 
  223. concern whatsoever for file breaks-- it treats the sequence of 
  224. files as a single source code stream.  
  225.  
  226. You should consider one or more of the following strategies, 
  227. which I have adopted in my source file management: 
  228.                                                           3-5
  229. 1. I name all my A86 source files with the same extension, which 
  230.    is found on no other files. The particular extension I have 
  231.    chosen is ".8". I did not choose the more common .ASM; because 
  232.    I have a few source-files designed for MSDOS's assembler.  If 
  233.    you don't like .8, I would suggest .A86.  
  234.  
  235. 2. I keep a separate sub-directory on my hard disk for each 
  236.    multi-source-file A86 program I have.  Then the simple command 
  237.    "A86 *.8" performs the assembly for the current directory's 
  238.    program.  
  239.  
  240. 3. I exploit the fact that A86 expands wild-cards into 
  241.    alphabetical order.  Whenever I want a source-file to be 
  242.    assembled first (e.g., when it contains variable 
  243.    declarations), I append a decimal digit to the start of the 
  244.    file name: 0 for the first file, 1 for the second, etc., for 
  245.    however many files that need to be explicitly ordered.  If a 
  246.    file needs to come last, I append a "Z" to the start of the 
  247.    file name.  
  248.  
  249.    To accommodate this strategy, I have programmed A86 to a 
  250.    somewhat complicated algorithm for determining the default 
  251.    output file-name.  I use the name of the first source file; 
  252.    but I truncate the first character if it is a decimal digit.  
  253.    However, you may have a general-purpose file that must come 
  254.    first; so I have provided the following exception: if you have 
  255.    a source-file whose name begins with the digit "9", that name 
  256.    (without the 9) is used.  If you don't like this, you can 
  257.    always explicitly give the program name you want: "A86 *.8 
  258.    MYPROG".  
  259.  
  260.  
  261.  
  262. System Requirements for A86
  263.  
  264. A86 requires MS-DOS V2.00 or later.  No BIOS or lower-level calls 
  265. are made by A86, so A86 should run on any MS-DOS machine.  Please 
  266. let me know if you find this not to be the case.  
  267.  
  268. To achieve its blazing speed, A86 is something of a memory hog. 
  269. A86 allocates separate segments for itself, its stack, its source 
  270. file, and its output file.  A86 itself now occupies about 20K; it 
  271. always takes a full 64K for the stack.  A86 splits the remaining 
  272. available memory between its source file and its output file.  It 
  273. allocates a minimum of 8K apiece; and a maximum of 64K apiece.   
  274. Thus A86 requires at least 100K; but it will consume up to 212K if 
  275. available.  
  276.  
  277. Careful reading of the above paragraph reveals that in a small-
  278. memory system A86 severely limits the size of source files.  But 
  279. remember that this doesn't hurt you badly: you can split up 
  280. source files with impunity.  A86 assembles a sequence of files as 
  281. if it were a single source stream (similar to the INCLUDE 
  282. facility of other assemblers).  
  283.  
  284.